Skip to main content

Front Matter Checker Tool

Overview​

The Front Matter Checker (FMC) is a command-line tool designed to analyze and optionally fix the front matter in markdown files, ensuring it adheres to a specified template format. This tool is ideal for developers managing markdown files in version-controlled repositories and seeking consistency in their front matter structures.

  • [Repo]
    • Note this repo will be empty for awhile, current work is on a cut-down (feature poor) version of this tool found in the snail to cheetah repo
  • Status:

IMPORTANT: This tool assumes that the files are part of a version control system (e.g., Git). It does not back up files before making changes but maintains a log of all changes. Users are responsible for committing changes to their repositories manually.

Features​

Required Flags​

Template​

  • -t | --template <path>: Specifies the path to the template file. An error is returned if the template does not exist.

Analyze or Fix​

  • analyze: Outputs the analysis of front matter without making any changes.

    • Output Format: 
      | FullPath       | Prop Name (Template)  | Prop Name (Template) | Prop Name (Not in Template) |
      |----------------|-----------------------|----------------------|-----------------------------|
      | <file path>    | missing | present     | hasValue             |
    • Properties specified in the template are listed before properties not in the template.

  • fix: Fixes front matter based on additional flags:

    Fix Options​

    • fullConform: Ensures complete conformity to the template.
      • Aligns properties to the specified order.
      • Removes extra properties.
      • Adds missing properties.
      • Generates IDs if specified in the template.
      • Ensures front matter starts on the first line.
    • allProps: Ensures all template properties are present.
    • fixOrder: Reorders properties to match the template.
    • removeExtraProps: Removes properties not defined in the template.

File Selection​

  • -dir <path>: Specifies a single directory (relative to the project root) to analyze or fix.
  • -files <file paths>: Specifies one or more files to process.

Optional Flags​

Value Insertion​

  • -genID: Generates an ID for missing or empty ID fields if specified in the template.
  • -vfc | --keyValuesFromConfig: Inserts key-value pairs defined in a configuration file. Requires the -config flag.
  • help: Displays the help information.

Configuration File​

The configuration file can specify value insertion rules using the valueInsertion property.

Format​

{
  "valueInsertion": {
    "prop": "value to insert",
    "anotherProp": ["value", "value"]
  }
}
  • Properties in the config file do not need to match the order in the template.

Workflow and Output​

  1. Program Output:

    • Displays the template and a summary of selected flags.
    • Asks for confirmation to proceed (Y/N).
    • Skippable by setting noCheck to true in the config file.

  2. Example Usage:

    fmc -t <template path> -analyze -dir ./myfolder/

    Analyzes files and prints the output table to the console.

    fmc -t <template path> -fix -fullConform -dir ./

    Fixes all files in the project to fully conform to the template.

    fmc -t <template path> -fix -allProps -dir ./myfolder/ -config <config path>

    Ensures all template properties are present, using key-value pairs from the configuration file.

Future Development Goals​

Learning Objectives​

  1. Implementing autocomplete for flags, potentially turning this into a YouTube series.
  2. Developing variations of the tool for different processing strategies:
    • Serial processing.
    • Parallel/concurrent processing.
    • Streaming.

Later Enhancements​

  • Conditional chaining: Add dynamic rules like, "If property X exists with value Y, then add property Z with value W."

Repository Information​

For the most up-to-date code and documentation, visit the GitHub repository.